PDFs aus Word-Vorlagen in Ruby generieren

Mit DocuGenerate können Sie PDF- und Word-Dokumente direkt aus Ihrer Ruby-Anwendung erstellen. Diese Anleitung zeigt, wie Sie jede API-Methode ab Ruby 3.0 aufrufen. Die vollständige Liste der Parameter und Antworten finden Sie in der API-Referenz.

Zusammenfassung

1. Authentifizierung
2. Vorlage erstellen
3. Vorlagen auflisten
4. Vorlage abrufen
5. Vorlage aktualisieren
6. Vorlage löschen
7. Dokument generieren
8. Dokumente auflisten
9. Dokument abrufen
10. Dokument aktualisieren
11. Dokument löschen

1. Authentifizierung

Jede Anfrage wird authentifiziert, indem Sie Ihren API-Schlüssel im Header Authorization senden. Speichern Sie den Schlüssel in einer Umgebungsvariable, statt ihn fest in Ihren Quellcode zu schreiben:

export DOCUGENERATE_API_KEY="YOUR-API-KEY"

Die Beispiele verwenden net/http und json aus der Ruby-Standardbibliothek, sodass nichts installiert werden muss. Sie verwenden alle diese Requires und Konstanten. Da net/http bei HTTP-Fehlerstatus keine Ausnahme auslöst, prüft jedes Beispiel die Antwort, bevor es sie liest:

require 'net/http'
require 'json'

API_URL = 'https://api.docugenerate.com/v1'
API_KEY = ENV['DOCUGENERATE_API_KEY']

Wenn Ihr Konto Daten in einer anderen Region speichert, ersetzen Sie die Basis-URL durch den passenden regionalen Endpunkt, zum Beispiel https://api.eu.docugenerate.com/v1.

2. Vorlage erstellen

Um eine Vorlage zu erstellen, laden Sie die Vorlagendatei mit einer Anfrage an POST /template hoch. Dieser Endpunkt erfordert den Inhaltstyp multipart/form-data, den set_form zusammen mit der Multipart-Boundary automatisch setzt:

uri = URI("#{API_URL}/template")
request = Net::HTTP::Post.new(uri)
request['Authorization'] = API_KEY
request['Accept'] = 'application/json'

File.open('Business Letter.docx') do |file|
  request.set_form(
    [
      ['file', file],
      ['name', 'Business Letter']
    ],
    'multipart/form-data'
  )
  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

  unless response.is_a?(Net::HTTPSuccess)
    raise "DocuGenerate API error #{response.code}: #{response.body}"
  end

  template = JSON.parse(response.body)
  puts template['id']
end

Setzen Sie den Header Content-Type nicht selbst, sonst fehlt die Boundary und die Anfrage schlägt fehl. Die Antwort enthält die neue Vorlage, einschließlich der automatisch in der Datei erkannten tags:

{
  "enhanced_syntax": false,
  "versioning_enabled": false,
  "folder": [],
  "tags": {
    "valid": [
      "Date",
      "Name",
      "Job Title",
      "Company Name",
      "Street Address",
      "City",
      "State",
      "Zip Code",
      "Email",
      "Phone"
    ],
    "invalid": []
  },
  "created": 1791055374301,
  "updated": 1791055374301,
  "name": "Business Letter",
  "delimiters": {
    "left": "[",
    "right": "]"
  },
  "filename": "Business Letter.docx",
  "format": ".docx",
  "region": "eu",
  "page_count": 1,
  "image_uri": "https://firebasestorage.googleapis.com/v0/b/storage.eu.docugenerate.com/o/templates%2FuVE30i1427KQsYcED0bl%2FBusiness%20Letter.png?alt=media&token=0ce64a4b-495a-426b-8783-42b479f7ae38",
  "preview_uri": "https://firebasestorage.googleapis.com/v0/b/storage.eu.docugenerate.com/o/templates%2FuVE30i1427KQsYcED0bl%2FBusiness%20Letter.pdf?alt=media&token=0b3939c7-824e-4979-9aca-ca4a87175cbf",
  "template_uri": "https://firebasestorage.googleapis.com/v0/b/storage.eu.docugenerate.com/o/templates%2FuVE30i1427KQsYcED0bl%2FBusiness%20Letter.docx?alt=media&token=d37a4458-3620-48db-94b8-6ac46f0442ab",
  "id": "uVE30i1427KQsYcED0bl"
}

Bewahren Sie die id der Vorlage auf, da Sie sie zum Generieren von Dokumenten benötigen. Die folgenden optionalen Parameter können ebenfalls dem Formular hinzugefügt werden:

delimiters: Die Begrenzer zur Erkennung der Tags, als JSON-String gesendet, z. B. { left: '[', right: ']' }.to_json. Standardmäßig werden sie automatisch ermittelt.
region: Wo die Vorlage und ihre generierten Dokumente gespeichert werden, entweder us, eu, uk oder au. Standardmäßig wird die Region des Kontos verwendet.
enhanced_syntax: Auf 'true' setzen, um verschachtelte Eigenschaften und logische oder mathematische Operatoren in den Tags zu verwenden.
versioning_enabled: Auf 'true' setzen, um beim Hochladen einer neuen Datei frühere Versionen zu behalten, sofern Ihr Plan dies erlaubt.
folder: Der Ordner der Vorlage, von der Wurzel bis zur untersten Ebene. Fehlende Ordner werden automatisch erstellt.

Um die Vorlage in einem Ordner abzulegen, fügen Sie für jede Ebene des Pfads ein folder-Feld hinzu. Zum Beispiel, um sie im Ordner Letters > Business abzulegen:

request.set_form(
  [
    ['file', file],
    ['name', 'Business Letter'],
    ['folder', 'Letters'],
    ['folder', 'Business']
  ],
  'multipart/form-data'
)

3. Vorlagen auflisten

Eine Anfrage an GET /template gibt alle Vorlagen in Ihrem Konto zurück:

uri = URI("#{API_URL}/template")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = API_KEY
request['Accept'] = 'application/json'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

unless response.is_a?(Net::HTTPSuccess)
  raise "DocuGenerate API error #{response.code}: #{response.body}"
end

templates = JSON.parse(response.body)
templates.each do |template|
  puts "#{template['id']} #{template['name']}"
end

Um nur die Vorlagen eines Ordners aufzulisten, wiederholen Sie den Abfrageparameter folder für jede Ebene des Pfads. Zum Beispiel, um die Vorlagen im Ordner Letters > Business aufzulisten:

uri = URI("#{API_URL}/template")
uri.query = URI.encode_www_form(
  [
    ['folder', 'Letters'],
    ['folder', 'Business']
  ]
)

request = Net::HTTP::Get.new(uri)
request['Authorization'] = API_KEY
request['Accept'] = 'application/json'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

unless response.is_a?(Net::HTTPSuccess)
  raise "DocuGenerate API error #{response.code}: #{response.body}"
end

Es werden nur die Vorlagen zurückgegeben, die direkt in diesem Ordner liegen. Vorlagen in seinen Unterordnern sind nicht enthalten. Erfahren Sie mehr darüber, wie Sie mit der API Vorlagen in Ordnern organisieren.

4. Vorlage abrufen

Um eine einzelne Vorlage abzurufen, rufen Sie GET /template/{id} mit ihrer ID auf:

template_id = 'bet2oQirk0pSd9ctH9Qu'

uri = URI("#{API_URL}/template/#{template_id}")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = API_KEY
request['Accept'] = 'application/json'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

unless response.is_a?(Net::HTTPSuccess)
  raise "DocuGenerate API error #{response.code}: #{response.body}"
end

template = JSON.parse(response.body)
puts template['tags']['valid']

Das ist zum Beispiel nützlich, um vor dem Generieren von Dokumenten zu prüfen, welche Zusammenführungs-Tags die Vorlage erwartet.

5. Vorlage aktualisieren

Eine Anfrage an PUT /template/{id} aktualisiert eine Vorlage. Alle Parameter sind optional, senden Sie also nur die, die Sie ändern möchten. Zum Beispiel, um eine neue Version der Datei hochzuladen und die Vorlage umzubenennen:

template_id = 'bet2oQirk0pSd9ctH9Qu'

uri = URI("#{API_URL}/template/#{template_id}")
request = Net::HTTP::Put.new(uri)
request['Authorization'] = API_KEY
request['Accept'] = 'application/json'

File.open('Business Letter v2.docx') do |file|
  request.set_form(
    [
      ['file', file],
      ['name', 'Business Letter v2']
    ],
    'multipart/form-data'
  )
  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

  unless response.is_a?(Net::HTTPSuccess)
    raise "DocuGenerate API error #{response.code}: #{response.body}"
  end

  template = JSON.parse(response.body)
end

Wie beim Erstellen einer Vorlage muss der Body multipart/form-data sein, was set_form zusammen mit der Multipart-Boundary automatisch setzt. Neben file und name können die folgenden optionalen Parameter dem Formular hinzugefügt werden:

delimiters: Die neuen Begrenzer, als JSON-String gesendet. Wenn sie angegeben werden, wird die Vorlage erneut analysiert, um die Zusammenführungs-Tags anhand der neuen Begrenzer zu erkennen. Wird ein neues file ohne delimiters hochgeladen, werden die aktuellen Begrenzer verwendet.
region: Verschiebt die Vorlage in eine andere Region, entweder us, eu, uk oder au. Danach generierte Dokumente werden in der neuen Region gespeichert, während bestehende Dokumente in ihrer aktuellen Region bleiben.
folder: Verschiebt die Vorlage in einen anderen Ordner, mit einem folder-Feld für jede Ebene des Pfads. Senden Sie '[]', um die Vorlage aus jedem Ordner herauszunehmen.
enhanced_syntax: Auf 'true' oder 'false' setzen, um die erweiterte Syntax zu aktivieren oder zu deaktivieren.
versioning_enabled: Auf 'true' oder 'false' setzen, um den Versionsverlauf zu aktivieren oder zu deaktivieren, sofern Ihr Plan dies erlaubt.

6. Vorlage löschen

Um eine Vorlage zu löschen, senden Sie eine Anfrage an DELETE /template/{id}. Die API antwortet bei Erfolg mit dem Status 204 No Content:

template_id = 'bet2oQirk0pSd9ctH9Qu'

uri = URI("#{API_URL}/template/#{template_id}")
request = Net::HTTP::Delete.new(uri)
request['Authorization'] = API_KEY
request['Accept'] = 'application/json'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

unless response.is_a?(Net::HTTPSuccess)
  raise "DocuGenerate API error #{response.code}: #{response.body}"
end

7. Dokument generieren

Sie generieren Dokumente mit einer Anfrage an POST /document, wobei Sie die template_id und die data übergeben, mit denen die Zusammenführungs-Tags ersetzt werden:

uri = URI("#{API_URL}/document")
request = Net::HTTP::Post.new(uri)
request['Authorization'] = API_KEY
request['Accept'] = 'application/json'
request['Content-Type'] = 'application/json'
request.body = {
  'template_id' => 'bet2oQirk0pSd9ctH9Qu',
  'data' => {
    'Date' => 'October 4, 2026',
    'Name' => 'Emily Carter',
    'Job Title' => 'Operations Manager',
    'Company Name' => 'Harbor Point Consulting',
    'Street Address' => '118 West Street',
    'City' => 'Annapolis',
    'State' => 'Maryland',
    'Zip Code' => '21405',
    'Email' => 'emily.carter@example.com',
    'Phone' => '(410) 555-0142'
  },
  'output_format' => '.pdf'
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

unless response.is_a?(Net::HTTPSuccess)
  raise "DocuGenerate API error #{response.code}: #{response.body}"
end

document = JSON.parse(response.body)
puts document['document_uri']

Die Antwort enthält die Eigenschaften des Dokuments:

{
  "created": 1791125416372,
  "template_id": "bet2oQirk0pSd9ctH9Qu",
  "name": "Business Letter",
  "format": ".pdf",
  "data_length": 1,
  "filename": "Business Letter.pdf",
  "document_uri": "https://firebasestorage.googleapis.com/v0/b/storage.us.docugenerate.com/o/documents%2FiESelthRt4uaYQRTemrL%2FBusiness%20Letter.pdf?alt=media&token=c4b259ec-249b-4b35-a62f-6a8dc0da75f3",
  "id": "iESelthRt4uaYQRTemrL"
}

Das output_format kann .docx (Standard), .pdf, .doc, .odt, .txt, .html, .png oder eine PDF/A-Version sein. Sie können außerdem mit merge_with PDF-Dateien am Ende des generierten Dokuments zusammenführen oder mit attach Anhänge hinzufügen.

Datei herunterladen
Die document_uri verweist auf die generierte Datei, die Sie herunterladen und auf der Festplatte speichern können:

file = Net::HTTP.get_response(URI(document['document_uri']))

unless file.is_a?(Net::HTTPSuccess)
  raise "Download failed with status #{file.code}"
end

File.binwrite(document['filename'], file.body)

Datei direkt empfangen
Wenn das Dokument nicht in der Cloud gespeichert werden soll, setzen Sie den Header Accept auf application/octet-stream. Die API antwortet dann mit der Binärdatei statt mit JSON:

uri = URI("#{API_URL}/document")
request = Net::HTTP::Post.new(uri)
request['Authorization'] = API_KEY
request['Accept'] = 'application/octet-stream'
request['Content-Type'] = 'application/json'
request.body = {
  'template_id' => 'bet2oQirk0pSd9ctH9Qu',
  'data' => {
    'Date' => 'October 4, 2026',
    'Name' => 'Emily Carter',
    'Job Title' => 'Operations Manager',
    'Company Name' => 'Harbor Point Consulting',
    'Street Address' => '118 West Street',
    'City' => 'Annapolis',
    'State' => 'Maryland',
    'Zip Code' => '21405',
    'Email' => 'emily.carter@example.com',
    'Phone' => '(410) 555-0142'
  },
  'output_format' => '.pdf'
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

unless response.is_a?(Net::HTTPSuccess)
  raise "DocuGenerate API error #{response.code}: #{response.body}"
end

File.binwrite('Business Letter.pdf', response.body)
puts response['X-Document-Id']

Batch-Dokumentgenerierung
Um mehrere Dokumente in einer Anfrage zu generieren, übergeben Sie ein Array von Hashes als data. Für jeden Hash wird ein Dokument generiert:

uri = URI("#{API_URL}/document")
request = Net::HTTP::Post.new(uri)
request['Authorization'] = API_KEY
request['Accept'] = 'application/json'
request['Content-Type'] = 'application/json'
request.body = {
  'template_id' => 'bet2oQirk0pSd9ctH9Qu',
  'data' => [
    { 'Date' => 'October 4, 2026', 'Name' => 'Emily Carter', 'Job Title' => 'Operations Manager', 'Company Name' => 'Harbor Point Consulting', 'Street Address' => '118 West Street', 'City' => 'Annapolis', 'State' => 'Maryland', 'Zip Code' => '21405', 'Email' => 'emily.carter@example.com', 'Phone' => '(410) 555-0142' },
    { 'Date' => 'October 4, 2026', 'Name' => 'Daniel Brooks', 'Job Title' => 'Logistics Coordinator', 'Company Name' => 'Northfield Logistics', 'Street Address' => '2400 South Lamar Boulevard', 'City' => 'Austin', 'State' => 'Texas', 'Zip Code' => '78704', 'Email' => 'daniel.brooks@example.com', 'Phone' => '(512) 555-0187' }
  ],
  'output_format' => '.pdf',
  'single_file' => true,
  'page_break' => true
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

unless response.is_a?(Net::HTTPSuccess)
  raise "DocuGenerate API error #{response.code}: #{response.body}"
end

document = JSON.parse(response.body)

Standardmäßig werden alle Dokumente in einer einzigen Datei zusammengefasst, mit einem Seitenumbruch nach jedem Dokument. Setzen Sie page_break auf false, um die Seitenumbrüche zu entfernen.

Wenn single_file auf false gesetzt ist, wird pro Datenobjekt eine Datei generiert, und alle Dateien werden in einem .zip-Archiv zusammengefasst. Verwenden Sie den Parameter name, um das Archiv zu benennen, und output_name mit Zusammenführungs-Tags, um jeder Datei einen dynamischen Namen zu geben, z. B. Letter for [Name]:

request.body = {
  'template_id' => 'bet2oQirk0pSd9ctH9Qu',
  'data' => [...],
  'output_format' => '.pdf',
  'single_file' => false,
  'name' => 'Business Letters',
  'output_name' => 'Letter for [Name]'
}.to_json

Dadurch entsteht ein Archiv Business Letters.zip mit Letter for Emily Carter.pdf und Letter for Daniel Brooks.pdf. Die Zusammenführungs-Tags in output_name müssen dieselben Begrenzer wie die Vorlage verwenden.

Datendatei verwenden
Um viele Dokumente auf einmal aus einer Excel- oder CSV-Datei zu generieren, senden Sie die Datei in einer multipart/form-data-Anfrage. Für jede Zeile der Tabelle wird ein Dokument generiert. Wenn die Datei mehrere Tabellenblätter enthält, geben Sie mit dem Parameter sheet an, welches verwendet werden soll.

uri = URI("#{API_URL}/document")
request = Net::HTTP::Post.new(uri)
request['Authorization'] = API_KEY
request['Accept'] = 'application/json'

File.open('Data.xlsx') do |file|
  request.set_form(
    [
      ['template_id', 'bet2oQirk0pSd9ctH9Qu'],
      ['file', file],
      ['output_format', '.pdf']
    ],
    'multipart/form-data'
  )
  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

  unless response.is_a?(Net::HTTPSuccess)
    raise "DocuGenerate API error #{response.code}: #{response.body}"
  end
end

Die Verwendung einer Datendatei ist eine weitere Form der Batch-Generierung, daher gelten dieselben Parameter, um die generierten Dokumente in einer einzigen Datei zusammenzufassen oder sie in einem .zip-Archiv mit einem eigenen Namen für jede Datei zu gruppieren.

8. Dokumente auflisten

Eine Anfrage an GET /document gibt die aus einer Vorlage generierten Dokumente zurück. Die ID der Vorlage wird im Abfrageparameter template_id übergeben:

uri = URI("#{API_URL}/document")
uri.query = URI.encode_www_form(template_id: 'bet2oQirk0pSd9ctH9Qu')

request = Net::HTTP::Get.new(uri)
request['Authorization'] = API_KEY
request['Accept'] = 'application/json'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

unless response.is_a?(Net::HTTPSuccess)
  raise "DocuGenerate API error #{response.code}: #{response.body}"
end

documents = JSON.parse(response.body)
documents.each do |document|
  puts "#{document['id']} #{document['name']} #{document['document_uri']}"
end

9. Dokument abrufen

Um ein einzelnes Dokument abzurufen, rufen Sie GET /document/{id} mit seiner ID auf:

document_id = 'iESelthRt4uaYQRTemrL'

uri = URI("#{API_URL}/document/#{document_id}")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = API_KEY
request['Accept'] = 'application/json'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

unless response.is_a?(Net::HTTPSuccess)
  raise "DocuGenerate API error #{response.code}: #{response.body}"
end

document = JSON.parse(response.body)

10. Dokument aktualisieren

Eine Anfrage an PUT /document/{id} benennt ein Dokument um, da der Name die einzige Eigenschaft ist, die geändert werden kann:

document_id = 'iESelthRt4uaYQRTemrL'

uri = URI("#{API_URL}/document/#{document_id}")
request = Net::HTTP::Put.new(uri)
request['Authorization'] = API_KEY
request['Accept'] = 'application/json'
request['Content-Type'] = 'application/json'
request.body = { 'name' => 'Letter for Emily Carter' }.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

unless response.is_a?(Net::HTTPSuccess)
  raise "DocuGenerate API error #{response.code}: #{response.body}"
end

document = JSON.parse(response.body)

11. Dokument löschen

Um ein Dokument zu löschen, senden Sie eine Anfrage an DELETE /document/{id}. Die API antwortet bei Erfolg mit dem Status 204 No Content:

document_id = 'iESelthRt4uaYQRTemrL'

uri = URI("#{API_URL}/document/#{document_id}")
request = Net::HTTP::Delete.new(uri)
request['Authorization'] = API_KEY
request['Accept'] = 'application/json'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

unless response.is_a?(Net::HTTPSuccess)
  raise "DocuGenerate API error #{response.code}: #{response.body}"
end

🆕 Ruby SDK

Vorlagen

Dokumente

Integrationen

Entwickler

Konto

API-SDKs